home *** CD-ROM | disk | FTP | other *** search
/ Aminet 44 / Aminet 44 (2001)(GTI - Schatztruhe)[!][Aug 2001].iso / Aminet / dev / src / ChunkyStartup2.lha / ChunkyStartup2K1 / cybergraphics.doc < prev    next >
Text File  |  2001-01-11  |  42KB  |  1,008 lines
  1. TABLE OF CONTENTS
  2.  
  3. cybergraphics.library/--background--
  4. cybergraphics.library/--bitmaps--
  5. cybergraphics.library/AllocCModeListTagList
  6. cybergraphics.library/BestCModeIDTagList
  7. cybergraphics.library/CModeRequestTagList
  8. cybergraphics.library/CVideoCtrlTagList
  9. cybergraphics.library/DoCDrawMethodTagList
  10. cybergraphics.library/FillPixelArray
  11. cybergraphics.library/FreeCModeList
  12. cybergraphics.library/GetCyberMapAttr
  13. cybergraphics.library/GetCyberIDAttr
  14. cybergraphics.library/InvertPixelArray
  15. cybergraphics.library/IsCyberModeID
  16. cybergraphics.library/LockBitMapTagList
  17. cybergraphics.library/MovePixelArray
  18. cybergraphics.library/ReadPixelArray
  19. cybergraphics.library/ReadRGBPixel
  20. cybergraphics.library/ScalePixelArray
  21. cybergraphics.library/WritePixelArray
  22. cybergraphics.library/WriteRGBPixel
  23. cybergraphics.library/UnLockBitMap
  24. cybergraphics.library/--background--      cybergraphics.library/--background--
  25.  
  26.    PURPOSE
  27.         cybergraphics.library is meant to be a gfx board extension for the
  28.         native graphics.library. Because C= never developed a rtg compliant
  29.         graphics.library (up to OS3.1 there are no possibilities to add custom
  30.         boards into the display database in a system friendly fashion), it
  31.         patches some of the original graphics functions in order to integrate
  32.         custom graphics boards into the system.
  33.          It also features some new functions which are not available in the
  34.         standard graphics.library. Currently graphics.library v39 and v40 is
  35.         supported.
  36.          Additionally it is possible to open screens deeper than 256 colours
  37.         which are completely intuition compatible. Nearly every function may
  38.         be used on such screen except some special blits which rely on planar
  39.         bitmap graphics. Also, this screens are 8bit backwards compatible.
  40.         Nearly every standard 8bit application will work on this 15/16/24 bit
  41.         screen. But it only can use the additional features, if it knows of
  42.         CyberGraphX, of course.
  43.          Maybe in a future release of graphics, CyberGraphX will be
  44.         obsolete.  But until then, cybergraphics.library is the only way to
  45.         add truecolour features to your application under an intuition
  46.         environment with minimum effort.
  47.          So, CyberGraphX is not meant to be a replacement for the original
  48.         graphics/intuition system (just like EGS is for example), e.g. there
  49.         is no ECS/AGA native chipset CyberGraphX driver, because all the
  50.         functionality of the original chipset is already given in the
  51.         original graphics.library.
  52.          Because of the different goal CyberGraphX spots in comparison to
  53.         EGS for example, it still may lack some features other systems have
  54.         already but it is perhaps the most system friendly graphics extension
  55.         the amiga computer family has seen so far.
  56.  
  57.         
  58.    OVERVIEW
  59.         This part only describes how to use the extended features of
  60.         CyberGraphX. Anything else about programming graphics can be found
  61.         in the original graphics.library documentation.
  62.  
  63. cybergraphics.library/--bitmaps--            cybergraphics.library/--bitmaps--
  64.  
  65. Bitmaps & CyberGraphX
  66.  
  67.  Before OS 3.x there was no standard method to create bitmaps.  It was up
  68. to the application programmer to allocate memory for the bitmap structure
  69. and to get the plane pointers by subsequent calls to AllocRaster()/gfx.  A
  70. InitBitMap() call was available to initialize various elements in the
  71. bitmap structure.
  72.  Unfortunately some people didn't even use AllocRaster() and InitBitmap()
  73. to setup their bitmaps but used AllocMem() and initialized the bitmap
  74. structure on their own.
  75.  Because there was only one certain bitplane format description, it was no
  76. problem to directly poke into the allocated planes.  It even was no problem
  77. to alter the contents of the bitmap structure because the application had
  78. total control over the location and the contents of this structure and
  79. related plane pointers.
  80.  
  81.  Starting with OS 3.x two new graphics calls were added to support bitmap
  82. creation and removal:  AllocBitmap()/gfx and FreeBitmap()/gfx.  With this
  83. calls the first step was made to allow custom bitmap formats.  Before it
  84. was no problem at all to directly render into the planes or to make
  85. assumptions about the structure of the bitmap data.  To get more
  86. information about the bitmap data an information retrieval call was added:
  87. GetBitmapAttr()/gfx.  With this one you could get information on the width,
  88. height, depth and certain flags of the bitmap.  This was the first step
  89. into the RTG direction.  As soon as GetBitmapAttr(bm,BMA_FLAGS) didn't
  90. return BMF_STANDARD, the bitmap was not direct accessable anymore and could
  91. only be accessed by attachment to a rastport and subsequent rendering calls
  92. or by using blit calls with a standard amiga bitmap as destination.
  93.  Unfortunately many programs didn't follow these guide lines and didn't
  94. check for the BMF_STANDARD flag with OS3.0 and above.  Up to now many
  95. programs still use the methods described at the beginning of this chapter.
  96. That's one reason why graphics extensions like CyberGraphX still have to
  97. fiddle around with planar to chunky conversions, even if the underlying
  98. hardware doesn't support planar graphics anymore.  This often leads to
  99. dramatic speed losses with certain applications which often could be
  100. redundant if standard rendering calls were used.
  101.  So please use AllocBitmap()/FreeBitmap() whereever possible when running
  102. 3.x.  It really gives you a major performance improvement in most cases
  103. when used on 3rd party display adapters.  Don't forget to add a friend
  104. bitmap pointer whereever possible to allocate compatible bitmap structures.
  105.  With CyberGraphX you also have to add BMF_MINPLANES in the flags field of
  106. AllocBitmap()/gfx.  This is due to bug in the standard picture.datatype
  107. which doesn't check for BMF_STANDARD and directly pokes into the bitplanes
  108. even if the returned bitmap is non planar ......  Using BMF_MINPLANES in a
  109. non CyberGraphX environment remains still compatible and should not lead to
  110. any problems, with CyberGraphX a chunky bitmap is returned, if a chunky
  111. friendbitmap is supplied.  How to access the bitmap data will be discussed
  112. later on.  Don't make assumptions on the bitmap contents before you have
  113. called the required CyberGraphX library calls !!
  114.  
  115.  Besides the AllocBitmap() friend bitmap method, AllocBitmap() has been
  116. extended to allow for allocation of certain pixel format bitmaps when using
  117. CyberGraphX.  With CyberGraphX, bitmaps aren't limited to planar image maps
  118. or 8 bit chunky data (which wasn't even available with the standard
  119. chipset/ graphics.library) anymore.  It is also possible now to allocate
  120. device dependant pixel format bitmaps and standard 15/16/24/32 bit depth
  121. image maps.  Therefore new bits in the 32bit flags field parameter of
  122. AllocBitmap() have been added.  If you specify the BMB_SPECIALFMT bit (see
  123. includes), the upper 8 bits of the flags longword contain information on
  124. the pixel format of the requested bitmap.  The following pixel formats are
  125. available:
  126.   PIXFMT_LUT8,PIXFMT_RGB15,PIXFMT_BGR15,PIXFMT_RGB15PC,PIXFMT_BGR15PC,
  127.   PIXFMT_RGB16,PIXFMT_BGR16,PIXFMT_RGB16PC,PIXFMT_BGR16PC,PIXFMT_RGB24,
  128.   PIXFMT_BGR24,PIXFMT_ARGB32,PIXFMT_BGRA32,PIXFMT_RGBA32 Many of this pixel
  129. formats are device specific and should not be used, recommended formats are
  130. PIXFMT_LUT8, PIXFMT_RGB16, PIXFMT_RGB24 and PIXFMT_ARGB32.
  131.  Once allocated, you can attach the returned bitmap to a rastport and do
  132. rendering calls.  It is NOT possible to attach this bitmap to a screen by
  133. supplying it as custom bitmap with OpenScreenTagList() !!
  134.  You are not allowed to directly poke into the bitmap image data as long as
  135. the bitmap isn't locked !.  The location and contents of the image data is
  136. subject to change and is only valid when it's locked by using the available
  137. locking calls (see autodocs).  LockBitmapTags()/UnLockBitmap() has been
  138. added for this purpose.  You HAVE TO supply a taglist with LockBitmapTags()
  139. which contains pointers to longwords which are filled with valid data if
  140. the call returns with a non-zero value.  Only if a non-zero value is
  141. returned you are able to access the bitmap directly !  Check the address
  142. you get back with the LBMI_BASEADDRESS tag.  This is the base address you
  143. can do your rendering to.  Get the value of the LBMI_PIXFMT ULONG field to
  144. get information on the colormodel you have to use for image rendering.  ALL
  145. models have to be supported!  The other fields give you information on the
  146. layout of the bitmap data.  It should be no problem, to directly render
  147. into the bitmap anymore.  Keep in mind that all this values are only valid
  148. until a subsequent call to UnLockBitmap().  Afterwards you have to lock the
  149. bitmap again.  Don't hold this lock for longer than one frame !  You may
  150. use the standard graphics.library bitmap blitting calls to copy the bitmap
  151. contents to another bitmap.  Copying truecolour bitmaps into indexed colour
  152. chunky bitmaps is not supported by now.
  153.  
  154. cybergraphics.library/AllocCModeListTagList cybergraphics.library/AllocCModeListTagList
  155.  
  156.    NAME
  157.         AllocCModeListTagList -- get an exec list with requested modes.
  158.         AllocCModeListTags -- Varargs stub for AllocCModeListTagList
  159.  
  160.    SYNOPSIS
  161.         result = AllocCModeListTagList( TagItems )
  162.         D0                               A1
  163.  
  164.         APTR AllocCModeListTagList( struct TagItem * );
  165.  
  166.         result = AllocCModeListTags( Tag1, ... )
  167.  
  168.         APTR AllocCModeListTags( Tag Tag1, ... );
  169.  
  170.    FUNCTION
  171.         Allocates a list structure which contains all requested modes (All nodes
  172.         are of type CyberModeNode). See defines for more information about the
  173.         structure of this nodes.
  174.  
  175.    INPUTS
  176.         TagItems - pointer to an optional tag list which may be used to
  177.                    control the number of returned modes
  178.  
  179.    TAGS
  180.         Tags available are:
  181.  
  182.         CYBRMREQ_MinWidth (ULONG) - The minimum display width to let the user
  183.                         choose. Default is 320.
  184.  
  185.         CYBRMREQ_MaxWidth (ULONG) - The maximum display width to let the user
  186.                         choose. Default is 1600.
  187.  
  188.         CYBRMREQ_MinHeight (ULONG) - The minimum display height to let the user
  189.                         choose. Default is 240.
  190.  
  191.         CYBRMREQ_MaxHeight (ULONG) - The maximum display height to let the user
  192.                         choose. Default is 1200.
  193.  
  194.         CYBRMREQ_MinDepth (UWORD) - The minimum display depth to let the user
  195.                         choose. Default is 8.
  196.  
  197.         CYBRMREQ_MaxDepth (UWORD) - The maximum display depth to let the user
  198.                         choose. Default is 32.
  199.  
  200.         CYBRMREQ_CModelArray (UWORD *) - Array of color models which should be
  201.                         available for screenmode selection. Currently supported
  202.                         colormodels are:
  203.                          PIXFMT_LUT8
  204.                          PIXFMT_RGB15
  205.                          PIXFMT_BGR15
  206.                          PIXFMT_RGB15PC
  207.                          PIXFMT_BGR15PC
  208.                          PIXFMT_RGB16
  209.                          PIXFMT_BGR16
  210.                          PIXFMT_RGB16PC
  211.                          PIXFMT_BGR16PC
  212.                          PIXFMT_RGB24
  213.                          PIXFMT_BGR24
  214.                          PIXFMT_ARGB32
  215.                          PIXFMT_BGRA32
  216.                          PIXFMT_RGBA32
  217.                         default is all colormodels available, nothing filtered
  218.  
  219.    RESULT
  220.         result - 0 if no modes are available, a pointer to a exec list if there
  221.                  are modes which fit your needs.
  222.  
  223.    SEE ALSO
  224.         FreeCModeList()
  225.  
  226. cybergraphics.library/BestCModeIDTagList   cybergraphics.library/BestCModeIDTagList
  227.  
  228.    NAME
  229.         BestCModeIDTagList -- calculate the best ModeID with given parameters
  230.         BestCModeIDTags -- Varags stub for BestCModeIDTagList
  231.  
  232.    SYNOPSIS
  233.         ID = BestCModeIDTagList( TagItems )
  234.         D0                          A0
  235.  
  236.         ULONG BestCModeIDTagList( struct TagItem * );
  237.  
  238.         ID = BestCModeIDTags( Tag1, ...)
  239.  
  240.         ULONG BestCModeIDTags( Tag, ... );
  241.  
  242.    FUNCTION
  243.         To determine the CyberGraphX displaymode id which fits best to the
  244.         parameters set in the TagList.
  245.  
  246.    INPUTS
  247.         TagItems - pointer to an array of TagItems
  248.  
  249.    TAGS
  250.         CYBRBIDTG_Depth (ULONG) - depth the returned ModeID must support
  251.                                   Default is 8
  252.  
  253.         CYBRBIDTG_NominalWidth (UWORD),
  254.         CYBRBIDTAG_NominalHeight (UWORD) - desired width and height the ModeID
  255.                                            should have
  256.  
  257.         CYBRBIDTG_MonitorID (ULONG) - if multiple graphics boards are
  258.                                       installed in the system, you can choose
  259.                                       the desired one with this tag
  260.  
  261.                                 Currently supported boards are:
  262.  
  263.                                         CYBERVISION
  264.                                         PICCOLO
  265.                                         PICASSO
  266.                                         SPECTRUM
  267.                                         DOMINO
  268.                                         RETINAZ3
  269.                                         PICCOSD64
  270.  
  271.    RESULT
  272.         ID - id of the best mode to use, or INVALID_ID if a match could
  273.              not be found.
  274.  
  275.    BUGS
  276.         Older versions return displaymode ids with wrong depth if the
  277.         desired color depth is not available.
  278.  
  279. cybergraphics.library/CModeRequestTagList    cybergraphics.library/CModeRequestTagList
  280.  
  281.    NAME
  282.         CModeRequestTagList -- get screenmode from user using a requester.
  283.         CModeRequestTags -- Varargs stub for CModeRequestTagList
  284.  
  285.    SYNOPSIS
  286.         result = CModeRequestTagList( Requester, TagItems )
  287.         D0                                A0        A1
  288.  
  289.         LONG CModeRequestTagList( APTR, struct TagItem * );
  290.  
  291.         result = CModeRequestTags( Requester, Tag1, ... )
  292.  
  293.         LONG CModeRequestTags( APTR, Tag, ...);
  294.  
  295.    FUNCTION
  296.         Prompts the user for input by showing all available cybergraphics
  297.         screenmodes in a requester.
  298.         If the user cancels or the system aborts the request, FALSE is returned,
  299.         otherwise the displaymode id of the selected screenmode.
  300.  
  301.    INPUTS
  302.         Requester - not used currently. You have to set it to NULL!
  303.         TagItems - pointer to an optional tag list which may be used to
  304.                    control features of the requester
  305.  
  306.    TAGS
  307.         Tags used for the screen mode requester
  308.  
  309.         CYBRMREQ_Screen (struct Screen *) - Screen on which to open the requester.
  310.                         default locale will be used.
  311.  
  312.         CYBRMREQ_WinTitle (STRPTR) - Title to use for the requesting window.
  313.  
  314.         CYBRMREQ_OKText (STRPTR) - Label of the positive gadget in the
  315.                         requester. English default is "OK".
  316.  
  317.         CYBRMREQ_CancelText (STRPTR) - Label of the negative gadget in the
  318.                         requester. English default is "Cancel".
  319.  
  320.         CYBRMREQ_MinWidth (ULONG) - The minimum display width to let the user
  321.                         choose. Default is 320.
  322.  
  323.         CYBRMREQ_MaxWidth (ULONG) - The maximum display width to let the user
  324.                         choose. Default is 1600.
  325.  
  326.         CYBRMREQ_MinHeight (ULONG) - The minimum display height to let the user
  327.                         choose. Default is 240.
  328.  
  329.         CYBRMREQ_MaxHeight (ULONG) - The maximum display height to let the user
  330.                         choose. Default is 1200.
  331.  
  332.         CYBRMREQ_MinDepth (UWORD) - The minimum display depth to let the user
  333.                         choose. Default is 8.
  334.  
  335.         CYBRMREQ_MaxDepth (UWORD) - The maximum display depth to let the user
  336.                         choose. Default is 32.
  337.  
  338.         CYBRMREQ_CModelArray (UWORD *) - Array of color models which should
  339.                         be available for screenmode selection. Currently
  340.                         supported colormodels are:
  341.  
  342.                         PIXFMT_LUT8
  343.                         PIXFMT_RGB15
  344.                         PIXFMT_BGR15
  345.                         PIXFMT_RGB15PC
  346.                         PIXFMT_BGR15PC
  347.                         PIXFMT_RGB16
  348.                         PIXFMT_BGR16
  349.                         PIXFMT_RGB16PC
  350.                         PIXFMT_BGR16PC
  351.                         PIXFMT_RGB24
  352.                         PIXFMT_BGR24
  353.                         PIXFMT_ARGB32
  354.                         PIXFMT_BGRA32
  355.                         PIXFMT_RGBA32
  356.  
  357.                         default is all colormodels available, nothing filtered
  358.  
  359.    RESULT
  360.         result - 0 if the user cancelled the requester or if something
  361.                  prevented the requester from opening. If!= 0 the displaymode
  362.                  id of the selected screenmode is returned.
  363.  
  364.    BUGS
  365.         The requester structure is not supported in (v40).
  366.  
  367.    NOTES
  368.         You should better use asl.library/AslRequest() instead.
  369.  
  370. cybergraphics.library/CVideoCtrlTagList cybergraphics.library/CVideoCtrlTagList
  371.  
  372.    NAME
  373.         CVideoCtrlTagList -- Control video output
  374.         CVideoCtrlTags -- Varargs stub for CVideoCtrlTagList
  375.  
  376.    SYNOPSIS
  377.         CVideoCtrlTagList( ViewPort, TagItems )
  378.                               A0        A1
  379.  
  380.         void CVideoCtrlTagList( struct ViewPort *, struct TagItem * );
  381.  
  382.         CVideoCtrlTags( ViewPort, Tag1, ... )
  383.  
  384.         void CVideoCtrlTags( struct ViewPort *, Tag tag1, ... );
  385.  
  386.    FUNCTION
  387.         This function controls the video output of the gfx board to which the
  388.         specified ViewPort belongs to.
  389.  
  390.    INPUTS
  391.         ViewPort - pointer to a ViewPort of a CyberGraphX screen
  392.         TagItems - taglist to control operation
  393.  
  394.    EXAMPLE
  395.         CVideoCtrlTags (&Scr->ViewPort,SETVC_DPMSLevel,DPMS_OFF,TAG_DONE);
  396.         /* set DPMS level */
  397.  
  398. cybergraphics.library/DoCDrawMethodTagList cybergraphics.library/DoCDrawMethodTagList
  399.  
  400.    NAME
  401.         DoCDrawMethodTagList -- Do the given hook for the supplied rastport
  402.         DoCDrawMethodTags -- Varargs stub for DoCDrawMethodTagList
  403.  
  404.    SYNOPSIS
  405.         DoCDrawMethodTagList( Hook, RastPort, TagItems )
  406.                                A0      A1        A2
  407.  
  408.         void DoCDrawMethodTagList( struct Hook *, struct RastPort *,
  409.                                    struct TagItem * )
  410.  
  411.         DoCDrawMethodTags( Hook, RastPort, Tag1, ... )
  412.  
  413.         void DoCDrawMethodTags( struct Hook *, struct RastPort *,
  414.                                 Tag1, ... )
  415.  
  416.    FUNCTION
  417.         This function will call the given hook for the given rastport. Is is
  418.         mainly used to do direct bitmap modifications in a locked graphics
  419.         environment. You have to support ALL known color models, so only use
  420.         this call if you really need it!!
  421.         
  422.  
  423.    INPUTS
  424.         Hook - pointer to callback hook which will be called
  425.                with object == (struct RastPort *)
  426.                and message == [ (APTR) memptr,
  427.                                 (ULONG) offsetx, (ULONG) offsety,
  428.                                 (ULONG) xsize, (ULONG) ysize,
  429.                                 (ULONG) bytesperrow, (UWORD) bytesperpix,
  430.                                 (UWORD) colormodel]
  431.                Where colormodel is one of the following:
  432.                         PIXFMT_LUT8
  433.                         PIXFMT_RGB15
  434.                         PIXFMT_BGR15
  435.                         PIXFMT_RGB15PC
  436.                         PIXFMT_BGR15PC
  437.                         PIXFMT_RGB16
  438.                         PIXFMT_BGR16
  439.                         PIXFMT_RGB16PC
  440.                         PIXFMT_BGR16PC
  441.                         PIXFMT_RGB24
  442.                         PIXFMT_BGR24
  443.                         PIXFMT_ARGB32
  444.                         PIXFMT_BGRA32
  445.                         PIXFMT_RGBA32
  446.         RastPort- A pointer to a cybergraphics RastPort
  447.         TagItems - optional taglist, currently not used. Set it to NULL!
  448.  
  449.    NOTES
  450.         Use this call only if you want high speed. Remember that you have to
  451.         handle all color models! Do not use ANY os functions in your hook.
  452.         They would cause unpredictable results.
  453.  
  454. cybergraphics.library/FreeCModeList       cybergraphics.library/FreeCModeList
  455.  
  456.    NAME
  457.         FreeCModeList -- frees a previously allocated ModeList
  458.  
  459.    SYNOPSIS
  460.         FreeCModeList( ModeList );
  461.                           A0
  462.  
  463.         void FreeCModeList( struct List * );
  464.  
  465.    FUNCTION
  466.         frees all data which was previously allocated by AllocCModeListTagList
  467.  
  468.    INPUTS
  469.         ModeList - a list structure which contains all the mode data.
  470.  
  471.    SEE ALSO
  472.         AllocCModeListTagList()
  473.  
  474. cybergraphics.library/GetCyberMapAttr    cybergraphics.library/GetCyberMapAttr
  475.  
  476.    NAME
  477.         GetCyberMapAttr -- Returns information about a cybergraphics bitmap
  478.  
  479.    SYNOPSIS
  480.         value = GetCyberMapAttr( BitMap, Attribute );
  481.          D0                        A0       D1
  482.  
  483.         ULONG GetCyberMapAttr( struct BitMap *, ULONG );
  484.  
  485.    FUNCTION
  486.         Determines information about a extended cybergraphics bitmap.
  487.         This function should be used instead of making any assumptions about
  488.         fields in the bitmap. This will provide future compatibility.
  489.  
  490.    INPUTS
  491.         BitMap - pointer to a cybergraphics bitmap structure
  492.  
  493.         Attribute - a number telling cybergraphics which attribute
  494.                     of the bitmap should be returned:
  495.  
  496.                     CYBRMATTR_XMOD        returns bytes per row of the
  497.                                           supplied bitmap
  498.  
  499.                     CYBRMATTR_BPPIX       returns number of bytes per pixel
  500.  
  501.                     CYBRMATTR_PIXFMT      return the pixel format of the
  502.                                           bitmap
  503.  
  504.                     CYBRMATTR_WIDTH       return width of the bitmap in
  505.                                           pixels
  506.  
  507.                     CYBRMATTR_HEIGHT      return the height in lines
  508.  
  509.                     CYBRMATTR_DEPTH       returns bits per pixel
  510.  
  511.                     CYBRMATTR_ISCYBERGFX  returns TRUE if supplied bitmap is
  512.                                           a CyberGraphX one
  513.  
  514.                     CYBRMATTR_ISLINEARMEM returns TRUE if the related display
  515.                                           buffer supports linear memory access
  516.  
  517.    NOTES
  518.         Unknown attributes are reserved for future use, and return (-1L).
  519.  
  520.         You should know what you are doing if you call this function!
  521.         Always use the CYBRMATTR_ISCYBERGFX attribute first to check if the
  522.         bitmap is a CyberGraphX one.
  523.  
  524. cybergraphics.library/GetCyberIDAttr    cybergraphics.library/GetCyberIDAttr
  525.  
  526.    NAME
  527.         GetCyberIDAttr -- Returns information about a cybergraphics id
  528.  
  529.    SYNOPSIS
  530.         value = GetCyberIDAttr( Attribute, DisplayModeID )
  531.           D0                       D0            D1
  532.  
  533.         ULONG GetCyberIDAttr( ULONG, ULONG );
  534.  
  535.    FUNCTION
  536.         Determines information about a specified displaymode id.
  537.  
  538.    INPUTS
  539.         Attribute - A number telling cybergraphics which attribute
  540.                     of the displaymode id should be returned:
  541.  
  542.                     CYBRIDATTR_PIXFMT return the pixel format of the supplied
  543.                                       screenmode id
  544.  
  545.                     CYBRIDATTR_WIDTH  returns visible width in pixels
  546.                     CYBRIDATTR_HEIGHT returns visible height in lines
  547.                     CYBRIDATTR_DEPTH  returns bits per pixel
  548.                     CYBRIDATTR_BPPIX  returns bytes per pixel
  549.  
  550.         DisplayModeID - CyberGraphX displaymode id
  551.  
  552.    NOTES
  553.         Unknown attributes are reserved for future use, and return (-1L).
  554.  
  555.         You should know what you are doing if you call this function!
  556.         Don't apply it on a non cybergraphics displaymode!
  557.  
  558. cybergraphics.library/IsCyberModeID       cybergraphics.library/IsCyberModeID
  559.  
  560.    NAME
  561.         IsCyberModeID -- returns whether supplied ModeID is a cybergraphics id
  562.  
  563.    SYNOPSIS
  564.         result = IsCyberModeID( DisplayModeID )
  565.         D0                            D0
  566.  
  567.         BOOL IsCyberModeID( ULONG );
  568.  
  569.    FUNCTION
  570.         returns whether the supplied ModeID is a cybergraphics.library mode
  571.         identifier.
  572.  
  573.    INPUTS
  574.         DisplayModeID -- a 32 bit display identifier.
  575.  
  576.    RESULT
  577.         result - Flag to indicate if DisplayModeID is a CyberGraphX id
  578.  
  579. cybergraphics.library/FillPixelArray     cybergraphics.library/FillPixelArray
  580.  
  581.    NAME
  582.         FillPixelArray -- fill a rectangular area with the supplied ARGB value
  583.         starting at a specified x,y location and continuing through to another
  584.         x,y location within a certain RastPort
  585.  
  586.    SYNOPSIS
  587.         count = FillPixelArray(RastPort,DestX, DestY,SizeX,SizeY,ARGB)
  588.         D0                        A1    D0:16  D1:16 D2:16 D3:16 D4:32
  589.                         
  590.  
  591.         LONG FillPixelArray( struct RastPort *, UWORD, UWORD,
  592.                              UWORD, UWORD, ULONG );
  593.  
  594.    FUNCTION
  595.         For each pixel in a rectangular region, write the supplied color value
  596.         into the bitmap used to describe a particular rastport.
  597.  
  598.    INPUTS
  599.         RastPort -  pointer to a RastPort structure
  600.         (DestX,DestY) - starting point in the RastPort
  601.         (SizeX,SizeY) - size of the rectangle that should be transfered
  602.         ARGB  - the desired color in AARRGGBB format. Every component
  603.                 allocates 8 bits of the returned longword. The coding is as
  604.                 follows:
  605.                  AA - 8-bit alpha channel component
  606.                       (set it to 00 if you do not use it!)
  607.                  RR - 8-bit red component of the pixel
  608.                  GG - 8-bit green component
  609.                  BB - 8-bit blue component
  610.  
  611.    RESULT
  612.         count will be set to the number of pixels plotted
  613.  
  614.    NOTES
  615.         This function should only be used on screens depths > 8 bits.
  616.  
  617. cybergraphics.library/InvertPixelArray   cybergraphics.library/InvertPixelArray
  618.  
  619.    NAME
  620.         InvertPixelArray -- invert a rectangular area
  621.  
  622.    SYNOPSIS
  623.         count = InvertPixelArray(RastPort,DestX, DestY,SizeX,SizeY)
  624.         D0                         A1     D0:16  D1:16 D2:16 D3:16
  625.                         
  626.  
  627.         LONG InvertPixelArray( struct RastPort *, UWORD, UWORD,
  628.                                UWORD,UWORD );
  629.  
  630.    FUNCTION
  631.         Invert each pixel in a rectangular region.
  632.  
  633.    INPUTS
  634.         RastPort -  pointer to a RastPort structure
  635.         (DestX,DestY) - starting point in the RastPort
  636.         (SizeX,SizeY) - size of the rectangle that should be transfered
  637.  
  638.    RESULT
  639.         count will be set to the number of pixels plotted
  640.  
  641.    NOTES
  642.         This function should only be used on screens depths > 8 bits.
  643.  
  644. cybergraphics.library/LockBitmapTagList cybergraphics.library/LockBitMapTagList
  645.  
  646.    NAME
  647.         LockBitMapTagList -- Lock supplied BitMap for a short amount of time
  648.                              to allow direct memory access
  649.  
  650.    SYNOPSIS
  651.         handle = LockBitmapTagList(bitmap,tags);
  652.         D0                           A0    A1
  653.  
  654.         APTR LockBitMapTagList( APTR,struct TagItem * );
  655.  
  656.         APTR LockBitMapTags( APTR,Tag1, ... );
  657.  
  658.    FUNCTION
  659.  
  660.    INPUTS
  661.         bitmap - pointer to a standard bitmap pointer. please check if it is
  662.                  a cybermap by calling GetCyberMapAttr() first.
  663.         tags - pointer to a mandatory taglist who's tagdata pointer fields
  664.                contain valid longwords after a successful call.
  665.  
  666.    TAGS
  667.         Tags used for the screen mode requester
  668.  
  669.         LBMI_WIDTH (ULONG *) - points to a longword which contains the bitmap
  670.                                width after a succesful call
  671.         LBMI_HEIGHT (ULONG *) - points to a longword which contains the bitmap
  672.                                 height after a succesful call
  673.         LBMI_DEPTH (ULONG *) - points to a longword which contains the bitmap
  674.                                depth after a successful call
  675.         LBMI_PIXFMT (ULONG *) - points to a longword which contains the used
  676.                                 pixel format.
  677.  
  678.                         Possibly returned colormodels are:
  679.  
  680.                         PIXFMT_LUT8
  681.                         PIXFMT_RGB15
  682.                         PIXFMT_BGR15
  683.                         PIXFMT_RGB15PC
  684.                         PIXFMT_BGR15PC
  685.                         PIXFMT_RGB16
  686.                         PIXFMT_BGR16
  687.                         PIXFMT_RGB16PC
  688.                         PIXFMT_BGR16PC
  689.                         PIXFMT_RGB24
  690.                         PIXFMT_BGR24
  691.                         PIXFMT_ARGB32
  692.                         PIXFMT_BGRA32
  693.                         PIXFMT_RGBA32
  694.  
  695.         LBMI_BYTESPERPIX (ULONG *) - points to a longword which contains the
  696.                                      amount of bytes per pixel data.
  697.         LBMI_BYTESPERROW (ULONG *) - points to a longword which contains the
  698.                                      number of bytes per row for one bitmap
  699.                                      line
  700.         LBMI_BASEADDRESS (ULONG *) - points to a longword which contains the
  701.                                      bitmap base address. THIS ADDRESS IS ONLY
  702.                                      VALID INSIDE OF THE LOCK/UNLOCKBITMAP
  703.                                      CALL!!!!!!!!!
  704.  
  705.  
  706.    RESULT
  707.         handle - 0 if the bitmap could not be locked,!= 0 it contains a handle
  708.                  which should be passed to UnLockBitMap afterwards
  709.  
  710.    NOTES
  711.         Only use this call if you really NEED the rendering speed, DON'T lock the
  712.         bitmap longer than for one frame. DON'T use any library calls while the
  713.         bitmap is locked! This function is considered low level.
  714.  
  715.    SEE ALSO
  716.         UnLockBitMap()
  717.  
  718. cybergraphics.library/MovePixelArray     cybergraphics.library/MovePixelArray
  719.  
  720.    NAME
  721.         MovePixelArray -- move the color values of a rectangular area of
  722.         pixels starting at a specified x,y location and continuing through
  723.         to another x,y location within a certain RastPort
  724.  
  725.    SYNOPSIS
  726.         count = MovePixelArray(SrcX, SrcY, RastPort,SrcX , SrcY ,SizeX, SizeY)
  727.         D0                     D0:16 D1:16  A1      D2:16  D3:16 D4:16  D5:16
  728.  
  729.         LONG MovePixelArray(UWORD,UWORD,struct RastPort *,UWORD,UWORD,UWORD,
  730.                                 UWORD)
  731.  
  732.    FUNCTION
  733.         For each pixel in a rectangular region, move the pixel value from a
  734.         specified source to a specified destination
  735.  
  736.    INPUTS
  737.         (SrcX,SrcY) - starting point in the destination rectangle
  738.         RastPort -  pointer to a RastPort structure
  739.         (DestX,DestY) - starting point in the destination rectangle
  740.         (SizeX,SizeY) - size of the rectangle that should be transfered
  741.  
  742.    RESULT
  743.         count will be set to the number of pixels moved
  744.  
  745.    NOTES
  746.         This function should only be used on screens depths > 8 bits.
  747.         The blitter can be used to move the data if the bitmap is in display
  748.         memory. This is why you should use this call.
  749.  
  750. cybergraphics.library/ReadPixelArray     cybergraphics.library/ReadPixelArray
  751.  
  752.    NAME
  753.         ReadPixelArray -- Read the color values of a rectangular array of
  754.         pixels starting at a specified x,y location and continuing through
  755.         to another x,y location within a certain RastPort
  756.  
  757.    SYNOPSIS
  758.         count = ReadPixelArray(destRect,DestX,DestY,DestMod,RastPort,SrcX ,
  759.         D0                        A0    D0:16 D1:16 D2:16     A1     D3:16
  760.                                 SrcY ,SizeX,SizeY,DestFormat)
  761.                                 D4:16 D5:16 D6:16    D7
  762.  
  763.         LONG ReadPixelArray(APTR,UWORD,UWORD,UWORD,struct RastPort *,UWORD,
  764.                             UWORD,UWORD,UWORD,UBYTE)
  765.  
  766.    FUNCTION
  767.         For each pixel in a rectangular region, write the color value to a
  768.         linear array of color values from the bitmap used to describe a
  769.         particular rastport.
  770.  
  771.    INPUTS
  772.         destRect - pointer to an array of pixels where to write the pixel
  773.                    data to. The pixel format is specified in DestFormat
  774.         (DestX,DestY) - starting point in the destination rectangle
  775.         DestMod - The number of bytes per row in the destination rectangle.
  776.         RastPort -  pointer to a RastPort structure
  777.         (SrcX,SrcY) - starting point in the RastPort
  778.         (SizeX,SizeY) - size of the rectangle that should be transfered
  779.         DestFormat - pixel format in the destination rectangle
  780.                     Currently supported formats are:
  781.  
  782.                     RECTFMT_RGB  3 bytes per pixel, one byte red, one blue
  783.                                  and one byte green component
  784.  
  785.                     RECTFMT_RGBA 4 bytes per pixel, one byte red, one blue,
  786.                                  one byte green component and the last
  787.                                  byte is alpha channel information which
  788.                                  is 0 if the board does not support alpha
  789.                                  channel
  790.  
  791.                     RECTFMT_ARGB 4 bytes per pixel, one byte red, one blue,
  792.                                  one byte green component and the first
  793.                                  byte is alpha channel information. If the
  794.                                  board does not support alpha channel a 
  795.                                  0 is returned for alpha channel information
  796.  
  797.    RESULT
  798.         count will be set to the number of pixels read
  799.  
  800.    NOTES
  801.         This function should only be used on screens depths > 8 bits.
  802.  
  803. cybergraphics.library/ReadRGBPixel          cybergraphics.library/ReadRGBPixel
  804.  
  805.    NAME
  806.         ReadRGBPixel -- Reads a pixel from a specified location
  807.  
  808.    SYNOPSIS
  809.         color = ReadRGBPixel(RastPort,x ,y )
  810.         D0                     A1     D0 D1
  811.  
  812.         ULONG ReadRGBPixel(struct RastPort *,UWORD,UWORD);
  813.  
  814.    FUNCTION
  815.         Read the Alpha,Red,Green & Blue 8-bit color value of the pixel at a
  816.         specified x,y location within a certain RastPort
  817.  
  818.    INPUTS
  819.         rp -  pointer to a RastPort structure
  820.         x,y    - the coordinates of the pixel
  821.  
  822.    RESULT
  823.         color  - the desired color in AARRGGBB format. Every component
  824.                  allocates 8 bits of the returned longword. The coding is as
  825.                  follows:
  826.  
  827.                  AA - 8-bit alpha channel component
  828.                       (boards which do not have an alpha channel return 00)
  829.                  RR - 8-bit red component of the pixel
  830.                  GG - 8-bit green component
  831.                  BB - 8-bit blue component
  832.  
  833.   NOTES
  834.         This function should only be used on screens depths > 8 bits. Use
  835.         ReadPixel() on 8 bit screens!
  836.  
  837. cybergraphics.library/ScalePixelArray   cybergraphics.library/ScalePixelArray
  838.  
  839.    NAME
  840.        ScalePixelArray -- Scale the colors values of a rectangular array of
  841.         pixels starting at a specified x,y location and continuing through
  842.         to another x,y location within a certain RastPort (V41)
  843.  
  844.    SYNOPSIS
  845.         count = ScalePixelArray(srcRect,SrcW,SrcH ,SrcMod,RastPort,DestX,
  846.         D0                         A0   D0:16 D1:16 D2:16     A1    D3:16
  847.                                 DestY,DestW,DestH,SrcFormat)
  848.                                 D4:16 D5:16 D6:16    D7
  849.  
  850.         LONG ScalePixelArray(APTR,UWORD,UWORD,UWORD,struct RastPort *,UWORD,
  851.                              UWORD,UWORD,UWORD,UBYTE)
  852.  
  853.    FUNCTION
  854.         For each pixel in a rectangular region, scale the color values from a
  855.         linear array of color values into the bitmap used to describe a
  856.         particular rastport.
  857.  
  858.    INPUTS
  859.         srcRect - pointer to an array of pixels from which to fetch the
  860.                   pixel data. The pixel format is specified in SrcFormat
  861.         (SrcW,SrcH) - Width and Height of the source rectangle
  862.         SrcMod - The n umber of bytes per row in the source rectangle.
  863.         RastPort -  pointer to a RastPort structure
  864.         (DestX,DestY) - starting point in the RastPort
  865.         (DestW,DestH) - size of the destination area
  866.         SrcFormat - pixel format in the source rectangle
  867.                     Currently supported formats are:
  868.  
  869.                     RECTFMT_RGB  3 bytes per pixel, one byte red, one blue
  870.                                  and one byte green component
  871.  
  872.                     RECTFMT_RGBA 4 bytes per pixel, one byte red, one blue,
  873.                                  one byte green component and the last
  874.                                  byte is alpha channel information. If you
  875.                                  do not use alpha channel set this byte to
  876.                                  0!!!
  877.  
  878.                     RECTFMT_ARGB 4 bytes per pixel, one byte red, one blue,
  879.                                  one byte green component and the first
  880.                                  byte is alpha channel information. If you
  881.                                  do not use alpha channel set this byte to
  882.                                  0!!!
  883.  
  884.    RESULT
  885.         count will be set to the number of pixels plotted
  886.  
  887.    NOTES
  888.         This function should only be used on screens depths > 8 bits.
  889.  
  890. cybergraphics.library/WritePixelArray   cybergraphics.library/WritePixelArray
  891.  
  892.    NAME
  893.         WritePixelArray -- write the color value of a rectangular array of
  894.         pixels starting at a specified x,y location and continuing through
  895.         to another x,y location within a certain RastPort
  896.  
  897.    SYNOPSIS
  898.         count = WritePixelArray(srcRect,SrcX ,SrcY ,SrcMod,RastPort,DestX,
  899.         D0                         A0   D0:16 D1:16 D2:16     A1    D3:16
  900.                                 DestY,SizeX,SizeY,SrcFormat)
  901.                                 D4:16 D5:16 D6:16    D7
  902.  
  903.         LONG WritePixelArray(APTR,UWORD,UWORD,UWORD,struct RastPort *,UWORD,
  904.                              UWORD,UWORD,UWORD,UBYTE)
  905.  
  906.    FUNCTION
  907.         For each pixel in a rectangular region, write the color value from a
  908.         linear array of color values into the bitmap used to describe a
  909.         particular rastport.
  910.  
  911.    INPUTS
  912.         srcRect - pointer to an array of pixels from which to fetch the
  913.                   pixel data. The pixel format is specified in SrcFormat
  914.         (SrcX,SrcY) - starting point in the source rectangle
  915.         SrcMod - The number of bytes per row in the source rectangle.
  916.         RastPort -  pointer to a RastPort structure
  917.         (DestX,DestY) - starting point in the RastPort
  918.         (SizeX,SizeY) - size of the rectangle that should be transfered
  919.         SrcFormat - pixel format in the source rectangle
  920.                     Currently supported formats are:
  921.  
  922.                     RECTFMT_RGB   3 bytes per pixel, one byte red, one blue
  923.                                   and one byte green component
  924.  
  925.                     RECTFMT_RGBA  4 bytes per pixel, one byte red, one
  926.                                   blue, one byte green component and the
  927.                                   last byte is alpha channel information.
  928.                                   If you do not use alpha channel set this
  929.                                   byte to 0!!!
  930.  
  931.                     RECTFMT_ARGB  4 bytes per pixel, one byte red, one
  932.                                   blue, one byte green component and the
  933.                                   first byte is alpha channel information.
  934.                                   If you do not use alpha channel set this
  935.                                   byte to 0!!!
  936.  
  937.                     RECTFMT_LUT8  1 byte per pixel, specifying the pen
  938.                                   number. On screen depths > 8 bits the
  939.                                   data is converted using the actual color
  940.                                   lookup table.
  941.  
  942.                     RECTFMT_GREY8 1 byte per pixel, specifying grey scale
  943.                                   value.
  944.  
  945.    RESULT
  946.         count will be set to the number of pixels plotted
  947.  
  948.    NOTES
  949.         Only RECTFMT_LUT8 can be used on screen depths <= 8 bits.
  950.  
  951. cybergraphics.library/WriteRGBPixel        cybergraphics.library/WriteRGBPixel
  952.  
  953.    NAME
  954.         WriteRGBPixel -- Writes a pixel to a specified location
  955.  
  956.    SYNOPSIS
  957.         error = WriteRGBPixel(RastPort,x ,y ,color)
  958.         D0                      A1     D0 D1 D2
  959.  
  960.         ULONG WriteRGBPixel(struct RastPort *,UWORD,UWORD,ULONG);
  961.  
  962.    FUNCTION
  963.         Write the Alpha,Red,Green & Blue 8-bit color value of the given color
  964.         to a specified x,y location within a certain RastPort
  965.  
  966.    INPUTS
  967.         rp     - pointer to a RastPort structure
  968.         x,y    - the coordinates of the pixel
  969.         color  - the desired color in AARRGGBB format. Every component
  970.                  allocates 8 bits of the returned longword. The coding is as
  971.                  follows:
  972.  
  973.                  AA - 8-bit alpha channel component
  974.                       (set it to 00 if you dont want to use it!)
  975.                  RR - 8-bit red component of the pixel
  976.                  GG - 8-bit green component
  977.                  BB - 8-bit blue component
  978.  
  979.    RESULT
  980.         error = 0 if pixel succesfully changed
  981.               = -1 if (x,y) is outside the rastport
  982.  
  983.    NOTES
  984.         This function should only be used on screens depths > 8 bits. Use
  985.         WritePixel() on 8 bit screens!
  986.  
  987. cybergraphics.library/UnLockBitmap           cybergraphics.library/UnLockBitMap
  988.  
  989.    NAME
  990.         UnLockBitMap -- UnLock CyberGraphX BitMap that was previously locked
  991.  
  992.    SYNOPSIS
  993.         UnLockBitmap( Handle )
  994.                         A0
  995.  
  996.         void UnLockBitMap( APTR );
  997.  
  998.    FUNCTION
  999.         UnLock CyberGraphX BitMap that was previously locked
  1000.  
  1001.    INPUTS
  1002.         handle - handle to the previously locked BitMap
  1003.  
  1004.    SEE ALSO
  1005.         LockBitMapTagList()
  1006.  
  1007.  
  1008.